Skip to content

feat: (W-003) Legacy compatibility adapter for 3.x to 4.0 migration#2015

Merged
bpamiri merged 3 commits intodevelopfrom
grove/W-003-wheels-4-0-legacy-compatibility-adapter-
Apr 8, 2026
Merged

feat: (W-003) Legacy compatibility adapter for 3.x to 4.0 migration#2015
bpamiri merged 3 commits intodevelopfrom
grove/W-003-wheels-4-0-legacy-compatibility-adapter-

Conversation

@bpamiri
Copy link
Copy Markdown
Collaborator

@bpamiri bpamiri commented Apr 3, 2026

Summary

Adds the wheels-legacy-adapter package — a backward compatibility layer for smooth migration from Wheels 3.x to 4.0.

  • DeprecationLogger — 4 severity modes (silent/log/warn/error), per-request deduplication, request-scoped tracking
  • LegacyAdapter — controller-scoped shims for renderPage()renderView() and renderPageToString()renderView(returnAs="string"), plus plugin diagnostics via $legacyPluginInfo()
  • MigrationScanner — detects 7 legacy patterns with path-aware filtering (plugin patterns restricted to plugins/ directory to avoid false positives)
  • 22 TestBox BDD specs covering all three components

Migration path

  1. Stage 1: Copy package to vendor/legacyadapter — existing 3.x code works unchanged
  2. Stage 2: Run migration scanner, update code incrementally (both old and new APIs work simultaneously)
  3. Stage 3: Set mode to error to catch stragglers, then remove adapter

Also includes

  • PR workflow label config for legacyadapter package
  • CI continue-on-error for auto-label job on fork PRs

Closes #1969

Test plan

  • All 22 adapter-specific specs pass (DeprecationLogger, LegacyAdapter, MigrationScanner)
  • Full core test suite passes on Lucee 6 (H2): 2278 pass, 0 fail, 0 error
  • Full core test suite passes on Adobe CF 2025 (SQLite): 2274 pass, 0 fail, 0 error
  • CI matrix passes across all engines

🤖 Generated with Claude Code

bpamiri and others added 3 commits April 3, 2026 11:03
Backward compatibility adapter that provides:
- DeprecationLogger with configurable modes (silent/log/warn/error)
- Controller mixin shims for deprecated APIs (renderPage, renderPageToString)
- MigrationScanner that analyzes app code for legacy patterns
- Three-stage progressive migration path (install → migrate → remove)

Verified on Lucee 6 and Adobe CF 2025. Core tests pass with 0 regressions.

Closes #1969

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Remove this.version from LegacyAdapter.cfc, source version from package.json
- Add pathFilter to MigrationScanner for context-aware this.version detection
  (only flags files in plugins/ directory, avoiding false positives)
- Remove $legacyPaginationLinks shim (no migration value)
- Move test-path check from inner loop to early return for efficiency
- Update tests: add path-filter verification, update $scanContent helper
  to accept subDir parameter for simulating file locations
- Revise plan: fix mixin scope to controller, demote Plugin-to-Package
  Bridge to Plugin Diagnostics, remove phantom showErrors setting,
  remove false-premise unresolved question, reframe edge cases

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…ter tests

DirectoryCreate(path, true) is Lucee-only — Adobe CF only accepts 1 parameter.
Replace with Java File.mkdirs() which works on all CFML engines.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@github-actions github-actions bot added docs dependencies Pull requests that update a dependency file javascript Pull requests that update javascript code labels Apr 3, 2026
@bpamiri bpamiri merged commit 180c8bb into develop Apr 8, 2026
3 checks passed
@bpamiri bpamiri deleted the grove/W-003-wheels-4-0-legacy-compatibility-adapter- branch April 8, 2026 12:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dependencies Pull requests that update a dependency file docs javascript Pull requests that update javascript code

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Wheels 4.0: Legacy compatibility adapter and migration path Issue #1969

1 participant